home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kio / job.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  21.3 KB  |  525 lines
  1. // -*- c++ -*-
  2. /* This file is part of the KDE libraries
  3.     Copyright (C) 2000 Stephan Kulow <coolo@kde.org>
  4.                        David Faure <faure@kde.org>
  5.  
  6.     This library is free software; you can redistribute it and/or
  7.     modify it under the terms of the GNU Library General Public
  8.     License as published by the Free Software Foundation; either
  9.     version 2 of the License, or (at your option) any later version.
  10.  
  11.     This library is distributed in the hope that it will be useful,
  12.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.     Library General Public License for more details.
  15.  
  16.     You should have received a copy of the GNU Library General Public License
  17.     along with this library; see the file COPYING.LIB.  If not, write to
  18.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.     Boston, MA 02110-1301, USA.
  20. */
  21.  
  22. #ifndef __kio_job_h__
  23. #define __kio_job_h__
  24.  
  25. #include <kio/jobclasses.h>
  26.  
  27. namespace KIO {
  28.  
  29.  
  30.     /**
  31.      * Creates a single directory.
  32.      *
  33.      *
  34.      *
  35.      *
  36.      * @param url The URL of the directory to create.
  37.      * @param permissions The permissions to set after creating the
  38.      *                    directory (unix-style), -1 for default permissions.
  39.      * @return A pointer to the job handling the operation.
  40.      */
  41.     KIO_EXPORT SimpleJob * mkdir( const KURL& url, int permissions = -1 );
  42.  
  43.     /**
  44.      * Removes a single directory.
  45.      *
  46.      * The directory is assumed to be empty.
  47.      *
  48.      *
  49.      *
  50.      * @param url The URL of the directory to remove.
  51.      * @return A pointer to the job handling the operation.
  52.      */
  53.     KIO_EXPORT SimpleJob * rmdir( const KURL& url );
  54.  
  55.     /**
  56.      * Changes permissions on a file or directory.
  57.      * See the other chmod below for changing many files
  58.      * or directories.
  59.      *
  60.      * @param url The URL of file or directory.
  61.      * @param permissions The permissions to set.
  62.      * @return the job handling the operation.
  63.      */
  64.     KIO_EXPORT SimpleJob * chmod( const KURL& url, int permissions );
  65.  
  66.     /**
  67.      * Rename a file or directory.
  68.      * Warning: this operation fails if a direct renaming is not
  69.      * possible (like with files or dirs on separate partitions)
  70.      * Use move or file_move in this case.
  71.      *
  72.      * @param src The original URL
  73.      * @param dest The final URL
  74.      * @param overwrite whether to automatically overwrite if the dest exists
  75.      * @return the job handling the operation.
  76.      */
  77.     KIO_EXPORT SimpleJob * rename( const KURL& src, const KURL & dest, bool overwrite );
  78.  
  79.     /**
  80.      * Create or move a symlink.
  81.      * This is the lowlevel operation, similar to file_copy and file_move.
  82.      * It doesn't do any check (other than those the slave does)
  83.      * and it doesn't show rename and skip dialogs - use KIO::link for that.
  84.      * @param target The string that will become the "target" of the link (can be relative)
  85.      * @param dest The symlink to create.
  86.      * @param overwrite whether to automatically overwrite if the dest exists
  87.      * @param showProgressInfo true to show progress information
  88.      * @return the job handling the operation.
  89.      */
  90.     KIO_EXPORT SimpleJob * symlink( const QString & target, const KURL& dest, bool overwrite, bool showProgressInfo = true );
  91.  
  92.     /**
  93.      * Execute any command that is specific to one slave (protocol).
  94.      *
  95.      * Examples are : HTTP POST, mount and unmount (kio_file)
  96.      *
  97.      * @param url The URL isn't passed to the slave, but is used to know
  98.      *        which slave to send it to :-)
  99.      * @param data Packed data.  The meaning is completely dependent on the
  100.      *        slave, but usually starts with an int for the command number.
  101.      * @param showProgressInfo true to show progress information
  102.      * @return the job handling the operation.
  103.      */
  104.     KIO_EXPORT SimpleJob * special( const KURL& url, const QByteArray & data, bool showProgressInfo = true );
  105.  
  106.     /**
  107.      * Mount filesystem.
  108.      *
  109.      * Special job for @p kio_file.
  110.      *
  111.      * @param ro Mount read-only if @p true.
  112.      * @param fstype File system type (e.g. "ext2", can be 0L).
  113.      * @param dev Device (e.g. /dev/sda0).
  114.      * @param point Mount point, can be @p null.
  115.      * @param showProgressInfo true to show progress information
  116.      * @return the job handling the operation.
  117.      */
  118.     KIO_EXPORT SimpleJob *mount( bool ro, const char *fstype, const QString& dev, const QString& point, bool showProgressInfo = true );
  119.  
  120.     /**
  121.      * Unmount filesystem.
  122.      *
  123.      * Special job for @p kio_file.
  124.      *
  125.      * @param point Point to unmount.
  126.      * @param showProgressInfo true to show progress information
  127.      * @return the job handling the operation.
  128.      */
  129.     KIO_EXPORT SimpleJob *unmount( const QString & point, bool showProgressInfo = true );
  130.  
  131.     /**
  132.      * HTTP cache update
  133.      *
  134.      * @param url Url to update, protocol must be "http".
  135.      * @param no_cache If true, cache entry for @p url is deleted.
  136.      * @param expireDate Local machine time indicating when the entry is
  137.      * supposed to expire.
  138.      * @return the job handling the operation.
  139.      */
  140.     KIO_EXPORT SimpleJob *http_update_cache( const KURL& url, bool no_cache, time_t expireDate);
  141.  
  142.     /**
  143.      * Find all details for one file or directory.
  144.      *
  145.      * @param url the URL of the file
  146.      * @param showProgressInfo true to show progress information
  147.      * @return the job handling the operation.
  148.      */
  149.     KIO_EXPORT StatJob * stat( const KURL& url, bool showProgressInfo = true );
  150.     /**
  151.      * Find all details for one file or directory.
  152.      * This version of the call includes two additional booleans, @p sideIsSource and @p details.
  153.      *
  154.      * @param url the URL of the file
  155.      * @param sideIsSource is true when stating a source file (we will do a get on it if
  156.      * the stat works) and false when stating a destination file (target of a copy).
  157.      * The reason for this parameter is that in some cases the kioslave might not
  158.      * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
  159.      * has issues with case-sensitivity on some systems).
  160.      * When the slave can't reliably determine the existence of a file, it will:
  161.      * @li be optimistic if sideIsSource=true, i.e. it will assume the file exists,
  162.      * and if it doesn't this will appear when actually trying to download it
  163.      * @li be pessimistic if sideIsSource=false, i.e. it will assume the file
  164.      * doesn't exist, to prevent showing "about to overwrite" errors to the user.
  165.      * If you simply want to check for existence without downloading/uploading afterwards,
  166.      * then you should use sideIsSource=false.
  167.      *
  168.      * @param details selects the level of details we want.
  169.      * By default this is 2 (all details wanted, including modification time, size, etc.),
  170.      * setDetails(1) is used when deleting: we don't need all the information if it takes
  171.      * too much time, no need to follow symlinks etc.
  172.      * setDetails(0) is used for very simple probing: we'll only get the answer
  173.      * "it's a file or a directory, or it doesn't exist". This is used by KRun.
  174.      * @param showProgressInfo true to show progress information
  175.      * @return the job handling the operation.
  176.      */
  177.     KIO_EXPORT StatJob * stat( const KURL& url, bool sideIsSource, short int details, bool showProgressInfo = true );
  178.  
  179.     /**
  180.      * Get (a.k.a. read).
  181.      *
  182.      * The slave emits the data through data().
  183.      * @param url the URL of the file
  184.      * @param reload true to reload the file, false if it can be taken from the cache
  185.      * @param showProgressInfo true to show progress information
  186.      * @return the job handling the operation.
  187.      */
  188.     KIO_EXPORT TransferJob *get( const KURL& url, bool reload=false, bool showProgressInfo = true );
  189.  
  190.     /**
  191.      * Put (a.k.a. write)
  192.      *
  193.      * @param url Where to write data.
  194.      * @param permissions May be -1. In this case no special permission mode is set.
  195.      * @param overwrite If true, any existing file will be overwritten.
  196.      * @param resume true to resume an operation. Warning, setting this to true means
  197.      *               that the data will be appended to @p dest if @p dest exists.
  198.      * @param showProgressInfo true to show progress information
  199.      * @return the job handling the operation.
  200.      * @see multi_get()
  201.      */
  202.     KIO_EXPORT TransferJob *put( const KURL& url, int permissions,
  203.                       bool overwrite, bool resume, bool showProgressInfo = true );
  204.  
  205.     /**
  206.      * HTTP POST (for form data).
  207.      *
  208.      * Example:
  209.      * \code
  210.      *    job = KIO::http_post( url, postData, false );
  211.      *    job->addMetaData("content-type", contentType );
  212.      *    job->addMetaData("referrer", referrerURL);
  213.      * \endcode
  214.      *
  215.      * @p postData is the data that you want to send and
  216.      * @p contentType is the complete HTTP header line that
  217.      * specifies the content's MIME type, for example
  218.      * "Content-Type: text/xml".
  219.      *
  220.      * You MUST specify content-type!
  221.      *
  222.      * Often @p contentType is
  223.      * "Content-Type: application/x-www-form-urlencoded" and
  224.      * the @p postData is then an ASCII string (without null-termination!)
  225.      * with characters like space, linefeed and percent escaped like %20,
  226.      * %0A and %25.
  227.      *
  228.      * @param url Where to write the data.
  229.      * @param postData Encoded data to post.
  230.      * @param showProgressInfo true to display
  231.      * @return the job handling the operation.
  232.      */
  233.     KIO_EXPORT TransferJob *http_post( const KURL& url, const QByteArray &postData,
  234.                             bool showProgressInfo = true );
  235.  
  236.     /**
  237.      * Get (a.k.a. read), into a single QByteArray.
  238.      * @see StoredTransferJob
  239.      *
  240.      * @param url the URL of the file
  241.      * @param reload true to reload the file, false if it can be taken from the cache
  242.      * @param showProgressInfo true to show progress information
  243.      * @return the job handling the operation.
  244.      * @since 3.3
  245.      */
  246.     KIO_EXPORT StoredTransferJob *storedGet( const KURL& url, bool reload=false, bool showProgressInfo = true );
  247.  
  248.     /**
  249.      * Put (a.k.a. write) data from a single QByteArray.
  250.      * @see StoredTransferJob
  251.      *
  252.      * @param arr The data to write
  253.      * @param url Where to write data.
  254.      * @param permissions May be -1. In this case no special permission mode is set.
  255.      * @param overwrite If true, any existing file will be overwritten.
  256.      * @param resume true to resume an operation. Warning, setting this to true means
  257.      *               that the data will be appended to @p dest if @p dest exists.
  258.      * @param showProgressInfo true to show progress information
  259.      * @return the job handling the operation.
  260.      * @since 3.3
  261.      */
  262.     KIO_EXPORT StoredTransferJob *storedPut( const QByteArray& arr, const KURL& url, int permissions,
  263.                                   bool overwrite, bool resume, bool showProgressInfo = true );
  264.  
  265.     /**
  266.      * Creates a new multiple get job.
  267.      *
  268.      * @param id the id of the get operation
  269.      * @param url the URL of the file
  270.      * @param metaData the MetaData associated with the file
  271.      *
  272.      * @return the job handling the operation.
  273.      * @see get()
  274.      */
  275.     KIO_EXPORT MultiGetJob *multi_get( long id, const KURL &url, const MetaData &metaData);
  276.  
  277.     /**
  278.      * Find mimetype for one file or directory.
  279.      *
  280.      * @param url the URL of the file
  281.      * @param showProgressInfo true to show progress information
  282.      * @return the job handling the operation.
  283.      */
  284.     KIO_EXPORT MimetypeJob * mimetype( const KURL& url,
  285.                             bool showProgressInfo = true );
  286.  
  287.     /**
  288.      * Copy a single file.
  289.      *
  290.      * Uses either SlaveBase::copy() if the slave supports that
  291.      * or get() and put() otherwise.
  292.      * @param src Where to get the file.
  293.      * @param dest Where to put the file.
  294.      * @param permissions May be -1. In this case no special permission mode is set.
  295.      * @param overwrite If true, any existing file will be overwritten.
  296.      * @param resume true to resume an operation. Warning, setting this to true means
  297.      *               that @p src will be appended to @p dest if @p dest exists.
  298.      *               You probably don't want that, so leave it to false :)
  299.      *
  300.      * @param showProgressInfo true to show progress information
  301.      * @return the job handling the operation.
  302.      */
  303.     KIO_EXPORT FileCopyJob *file_copy( const KURL& src, const KURL& dest, int permissions=-1,
  304.                             bool overwrite=false, bool resume=false,
  305.                             bool showProgressInfo = true);
  306.  
  307.     /**
  308.      * Move a single file.
  309.      *
  310.      * Use either SlaveBase::rename() if the slave supports that,
  311.      * or copy() and del() otherwise, or eventually get() & put() & del()
  312.      * @param src Where to get the file.
  313.      * @param dest Where to put the file.
  314.      * @param permissions May be -1. In this case no special permission mode is set.
  315.      * @param overwrite If @p true, any existing file will be overwritten.
  316.      * @param resume true to resume an operation. Warning, setting this to true means
  317.      *               that @p src will be appended to @p dest if @p dest exists.
  318.      *               You probably don't want that, so leave it to false :)
  319.      * @param showProgressInfo true to show progress information
  320.      * @return the job handling the operation.
  321.      */
  322.     KIO_EXPORT FileCopyJob *file_move( const KURL& src, const KURL& dest, int permissions=-1,
  323.                             bool overwrite=false, bool resume=false,
  324.                             bool showProgressInfo = true);
  325.  
  326.     /**
  327.      * Delete a single file.
  328.      *
  329.      * @param src File to delete.
  330.      * @param showProgressInfo true to show progress information
  331.      * @return the job handling the operation.
  332.      */
  333.     KIO_EXPORT SimpleJob *file_delete( const KURL& src, bool showProgressInfo = true);
  334.  
  335.     /**
  336.      * List the contents of @p url, which is assumed to be a directory.
  337.      *
  338.      * "." and ".." are returned, filter them out if you don't want them.
  339.      *
  340.      *
  341.      * @param url the url of the directory
  342.      * @param showProgressInfo true to show progress information
  343.      * @param includeHidden true for all files, false to cull out UNIX hidden
  344.      *                      files/dirs (whose names start with dot)
  345.      * @return the job handling the operation.
  346.      */
  347.     KIO_EXPORT ListJob *listDir( const KURL& url, bool showProgressInfo = true,
  348.                       bool includeHidden = true );
  349.  
  350.     /**
  351.      * The same as the previous method, but recurses subdirectories.
  352.      * Directory links are not followed.
  353.      *
  354.      * "." and ".." are returned but only for the toplevel directory.
  355.      * Filter them out if you don't want them.
  356.      *
  357.      * @param url the url of the directory
  358.      * @param showProgressInfo true to show progress information
  359.      * @param includeHidden true for all files, false to cull out UNIX hidden
  360.      *                      files/dirs (whose names start with dot)
  361.      * @return the job handling the operation.
  362.      */
  363.     KIO_EXPORT ListJob *listRecursive( const KURL& url, bool showProgressInfo = true,
  364.                             bool includeHidden = true );
  365.  
  366.     /**
  367.      * Copy a file or directory @p src into the destination @p dest,
  368.      * which can be a file (including the final filename) or a directory
  369.      * (into which @p src will be copied).
  370.      *
  371.      * This emulates the cp command completely.
  372.      *
  373.      * @param src the file or directory to copy
  374.      * @param dest the destination
  375.      * @param showProgressInfo true to show progress information
  376.      * @return the job handling the operation
  377.      * @see copyAs()
  378.      */
  379.     KIO_EXPORT CopyJob *copy( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  380.  
  381.     /**
  382.      * Copy a file or directory @p src into the destination @p dest,
  383.      * which is the destination name in any case, even for a directory.
  384.      *
  385.      * As opposed to copy(), this doesn't emulate cp, but is the only
  386.      * way to copy a directory, giving it a new name and getting an error
  387.      * box if a directory already exists with the same name.
  388.      *
  389.      * @param src the file or directory to copy
  390.      * @param dest the destination
  391.      * @param showProgressInfo true to show progress information
  392.      * @return the job handling the operation
  393.      */
  394.     KIO_EXPORT CopyJob *copyAs( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  395.  
  396.     /**
  397.      * Copy a list of file/dirs @p src into a destination directory @p dest.
  398.      *
  399.      * @param src the list of files and/or directories
  400.      * @param dest the destination
  401.      * @param showProgressInfo true to show progress information
  402.      * @return the job handling the operation
  403.      */
  404.     KIO_EXPORT CopyJob *copy( const KURL::List& src, const KURL& dest, bool showProgressInfo = true );
  405.  
  406.     /**
  407.      * Moves a file or directory @p src to the given destination @p dest.
  408.      *
  409.      * @param src the file or directory to copy
  410.      * @param dest the destination
  411.      * @param showProgressInfo true to show progress information
  412.      * @return the job handling the operation
  413.      * @see copy()
  414.      * @see moveAs()
  415.      */
  416.     KIO_EXPORT CopyJob *move( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  417.     /**
  418.      * Moves a file or directory @p src to the given destination @p dest. Unlike move()
  419.      * this operation will fail when the directory already exists.
  420.      *
  421.      * @param src the file or directory to copy
  422.      * @param dest the destination
  423.      * @param showProgressInfo true to show progress information
  424.      * @return the job handling the operation
  425.      * @see copyAs()
  426.      */
  427.     KIO_EXPORT CopyJob *moveAs( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  428.     /**
  429.      * Moves a list of files or directories @p src to the given destination @p dest.
  430.      *
  431.      * @param src the list of files or directories to copy
  432.      * @param dest the destination
  433.      * @param showProgressInfo true to show progress information
  434.      * @return the job handling the operation
  435.      * @see copy()
  436.      */
  437.     KIO_EXPORT CopyJob *move( const KURL::List& src, const KURL& dest, bool showProgressInfo = true );
  438.  
  439.     /**
  440.      * Create a link.
  441.      * If the protocols and hosts are the same, a Unix symlink will be created.
  442.      * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
  443.      *
  444.      * @param src The existing file or directory, 'target' of the link.
  445.      * @param destDir Destination directory where the link will be created.
  446.      * @param showProgressInfo true to show progress information
  447.      * @return the job handling the operation
  448.      */
  449.     KIO_EXPORT CopyJob *link( const KURL& src, const KURL& destDir, bool showProgressInfo = true );
  450.  
  451.     /**
  452.      * Create several links
  453.      * If the protocols and hosts are the same, a Unix symlink will be created.
  454.      * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
  455.      *
  456.      * @param src The existing files or directories, 'targets' of the link.
  457.      * @param destDir Destination directory where the links will be created.
  458.      * @param showProgressInfo true to show progress information
  459.      * @return the job handling the operation
  460.      * @see link()
  461.      */
  462.     KIO_EXPORT CopyJob *link( const KURL::List& src, const KURL& destDir, bool showProgressInfo = true );
  463.  
  464.     /**
  465.      * Create a link. Unlike link() this operation will fail when the directory already
  466.      * exists.
  467.      * If the protocols and hosts are the same, a Unix symlink will be created.
  468.      * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
  469.      *
  470.      * @param src The existing file or directory, 'target' of the link.
  471.      * @param dest Destination directory where the link will be created.
  472.      * @param showProgressInfo true to show progress information
  473.      * @return the job handling the operation
  474.      * @see link ()
  475.      * @see copyAs()
  476.      */
  477.     KIO_EXPORT CopyJob *linkAs( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  478.  
  479.     /**
  480.      * Trash a file or directory.
  481.      * This is currently only supported for local files and directories.
  482.      * Use "KURL src; src.setPath( path );" to create a URL from a path.
  483.      *
  484.      * @param src file to delete
  485.      * @param showProgressInfo true to show progress information
  486.      * @return the job handling the operation
  487.      * @since 3.4
  488.      */
  489.     KIO_EXPORT CopyJob *trash( const KURL& src, bool showProgressInfo = true );
  490.  
  491.     /**
  492.      * Trash a list of files or directories.
  493.      * This is currently only supported for local files and directories.
  494.      *
  495.      * @param src the files to delete
  496.      * @param showProgressInfo true to show progress information
  497.      * @return the job handling the operation
  498.      * @since 3.4
  499.      */
  500.     KIO_EXPORT CopyJob *trash( const KURL::List& src, bool showProgressInfo = true );
  501.  
  502.     /**
  503.      * Delete a file or directory.
  504.      *
  505.      * @param src file to delete
  506.      * @param shred obsolete (TODO remove in KDE4)
  507.      * @param showProgressInfo true to show progress information
  508.      * @return the job handling the operation
  509.      */
  510.     KIO_EXPORT DeleteJob *del( const KURL& src, bool shred = false, bool showProgressInfo = true );
  511.  
  512.     /**
  513.      * Deletes a list of files or directories.
  514.      *
  515.      * @param src the files to delete
  516.      * @param shred obsolete (TODO remove in KDE4)
  517.      * @param showProgressInfo true to show progress information
  518.      * @return the job handling the operation
  519.      */
  520.     KIO_EXPORT DeleteJob *del( const KURL::List& src, bool shred = false, bool showProgressInfo = true );
  521. }
  522.  
  523. #endif
  524.  
  525.